.TH E1432_SET_DECIMATION_UNDERSAMP 3 E1432
.SH NAME
.nf
e1432_set_decimation_undersamp \- Set digital filter undersample amount
e1432_get_decimation_undersamp \- Get digital filter undersample amount
.fi
.IX e1432_set_decimation_undersamp(3) 3
.IX e1432_get_decimation_undersamp(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_set_decimation_undersamp(E1432ID hw, SHORTSIZ16 ID,
                                          SHORTSIZ16 undersamp)
SHORTSIZ16 e1432_get_decimation_undersamp(E1432ID hw, SHORTSIZ16 ID,
                                          SHORTSIZ16 *undersamp)
.cE
.SH DESCRIPTION

This function is not needed by most normal users.  It works only for
the E1433 module, is useful only in certain specific applications, and
can reduce the alias protection normally provided by the E1433 module.

\fIe1432_set_decimation_undersamp\fR causes the input ADC to get run
at a slower clock frequency than normal.  The input ADC clock
frequency is normally specified by \fIe1432_set_clock_freq\fR.  When
\fIe1432_set_decimation_undersamp\fR is used, the normal clock
frequency is divided by the undersample amount.

The slower "undersampled" clock frequency means that data is sampled
at a slower rate, reducing the amount of decimation filtering that
must be done by the input signal processors to produce data at the
span specified by \fIe1432_set_span\fR.  If the undersample amount is
equal to the total amount of decimation that must be done, then the
input signal processors will not have to do any decimation filtering.
This setting has the advantage of not running the data through the
normal non-linear-phase decimation filters, which can be useful for
time-domain measurements.

\fIe1432_get_decimation_undersamp\fR returns the current amount of the
undersampling, of a single channel or group of channels \fIID\fR, into
a memory location pointed to by \fIundersamp\fR.

This parameter is a "global" parameter.  It applies to an entire E1432
module rather than to one of its channels.  The \fIID\fR parameter is
used only to identify which module the function applies to, and all
channels in that module will report the same value for this parameter.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fIID\fR is either the ID of a group of channels that was obtained
with a call to \fIe1432_create_channel_group\fR, or the ID of a single
channel.

\fIundersamp\fR specifies the amount of undersampling.  A value of 1
means no undersampling.  Higher values specify more undersampling.
This undersampling is supported only the the E1433 module.  A value
greater than 1 will result in an error on an E1432 module.

The \fIundersamp\fR amount will be rounded up to the next highest
power of two.  The resulting undersample amount must not be larger
than 16, or an error will be produced.  In addition, if the
undersample reduces the effective ADC clock frequency to less than
7812.5 Hz (the minimum specified by the ADC manufacturer), an error
will be produced.

The undersample amount must not be larger than the amount of
decimation needed to produce data at the current span.  The
undersampling can be done when the module is producing "oversampled"
data (see \fIe1432_set_decimation_oversample\fR).  In this case, the
undersample amount must be \fIless\fR than the amount of decimation
needed to produce data at the current span, so that the input
decimation filters run at least once, so that oversampled data can be
produced.

As an example, suppose the clock frequency is 65536 Hz and the current
span is 6400 Hz.  The data rate is 6400 * 2.56 = 16384 samples per
second, and the decimation filters must do two passes of
decimate-by-two, for a total decimation of four, to produce that.  In
this case, the undersample value can be 1, 2, or 4.  The value of 4
causes no decimation filtering to take place.  If oversample is turned
on, then the undersample value must be either 1 or 2.

.ne 7
Undersampling by more than one has the following limitations and
drawbacks:
.nf
    * It works only on E1433 modules
    * No zoom can be done
    * Alias protection is reduced, potentially by a great deal
.fi
Because of these drawbacks, this setting is probably only useful in
special circumstances.

Even if the undersample amount prevents the non-linear-phase
decimation filters from being used, the ADC itself has a linear-phase
digital filter which can't be disabled.  This is similar to all
Delta-Sigma converters, which all have a built-in anti-alias filter.

Because these ADC filters are linear-phase, they produce less
distortion of the input time waveform than typical non-linear-phase
decimation filters.  For this reason, they are generally preferred for
time-domain applications.

The undersampling reduces alias protection, but in ways that may not
be a problem for many applications.  The aliasing is \fBonly\fR at 32
times the effective sample clock frequency, due to the ADC's built-in
digital filter.

For example, suppose the sample clock frequency is set to 65536 Hz,
and the undersample amount is 2.  The effective sample rate of the
data produced by the input ADCs is then 32768 Hz.  Any potential alias
products would be at 32 * 32768, which is about 1 MHz.  Most normal
measurement signals have no energy at this frequency, so the aliasing
is probably not a problem.

Furthermore, even if there was energy out at this frequency, it is
still somewhat attenuated by the analog anti-alias filters.  The
amount of attenuation varies with clock frequency.  Typical alias
attenuation to expect is given in the following table.

.ne 8
.TS
box center;
c s s
c | c | c.
Typical Undersample Alias Attenuation
_
Effective	Minimum	Typical Alias
Clock Freq	Alias Freq	Protection
=
65536 Hz	2 MHz	>90 dB
32768 Hz	1 MHz	70 dB
16384 Hz	524 kHz	35 dB
8192 Hz	262 kHz	0 dB
.TE

.SH "RESET VALUE"
After a reset, \fIundersamp\fR is set to 1.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.SH "SEE ALSO"
.na
e1432_set_decimation_output, e1432_set_decimation_oversample,
e1432_set_span, e1432_set_clock_freq, e1432_set_anti_alias_digital
.ad
